feat: implement SEP-1699 SSE polling via server-side disconnect #1129

felixweinberger · 2025-11-17T14:45:20Z

Summary

Implements SEP-1699 which enables servers to disconnect SSE connections at will by sending priming events and retry fields.

Motivation and Context

SEP-1699 introduces SSE polling behavior that allows servers to control client reconnection timing and close connections gracefully. This enables more efficient resource management on the server side while maintaining resumability.

We implement this on the POST SSE stream as implied by the SEP language linked above. I.e. when a server establishes an SSE stream:

It's first message will be an event including no data, only an event ID.
After that, it may call cancelSSEStream to close the stream while still gathering the events.
The client can start "polling" the SSE stream based on the retryInterval supplied by the server before disconnection.

How Has This Been Tested?

Added e2e integration tests demonstrating the initial priming message, disconnection initiated by the server, and subsequent reconnection via polling by the client.
[currently WIP] upcoming conformance tests in feat: add conformance tests for SEP-1699 SSE polling conformance#47

Breaking Changes

None. Client falls back to exponential backoff if no retry field is provided.

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

pkg-pr-new · 2025-11-17T14:46:05Z

Open in StackBlitz

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/sdk@1129

commit: 0b1898b

felixweinberger · 2025-11-17T21:16:22Z

src/server/streamableHttp.test.ts

+        toolResolve!();
+    });
+
+    it('should support POST SSE polling with client reconnection', async () => {


probably the most interesting test

felixweinberger · 2025-11-17T21:22:15Z

src/server/streamableHttp.test.ts

+        const primingEventId = primingIdMatch![1];
+
+        // Server closes the stream to trigger polling
+        transport.closeSSEStream(100);


this feels slightly weird. The whole point is for the server to be able to close SSE streams, so maybe this method should be exposed on server?

On the other hand, this disconnection only makes sense in the SHTTP transport - whereas the server is actually transport agnostic.

Maybe the correct expectation is to have the server call this method directly via its reference to the transport if necessary and actually available, so this might be fine actually.`

I think this should be called by the user on the server. A bunch of frameworks dont give the user easy access to the transport but they do the server. Proxy by reference is good

To me it would feel very weird to have a closeSSEStream on the server that should have no knowledge of sessions let alone streams.

A bunch of frameworks dont give the user easy access to the transport but they do the server. Proxy by reference is good

This is a good point but maybe the right API is to expose the transport from the server?

Add support for SSE retry field to enable server-controlled client reconnection timing. Client changes: - Capture server-provided retry field from SSE events - Use retry value for reconnection delay instead of exponential backoff - Reconnect on graceful stream close with Last-Event-ID header Server changes: - Add retryInterval option to StreamableHTTPServerTransportOptions - Send priming events with id/retry/empty-data when eventStore is configured - Add closeSSEStream(requestId) API to close POST SSE streams for polling - Priming events establish resumption capability before actual messages Tests: - Client: retry field capture, exponential backoff fallback, graceful reconnection - Server: priming events, retry field, stream closure, POST SSE polling flow

felixweinberger · 2025-11-18T11:30:12Z

Hi @jonathanhefner would love feedback on whether this accurately captures the intent of your original SEP

@paoloricciuti in case you want to TAL as you had valuable input on modelcontextprotocol/conformance#35

paoloricciuti

So we actually had a brief discussion about this on discord and I think the spec should be clearer here: from the discussion we had the reconnection should be different from the standalone stream. So if the client was doing two POST requests each POST would have it's own lastEventId.

On reconnect this should basically result in 3 new GET SSE streams, two to get the remaining notificiations/responses from the POST requests and one as a standalone stream for the new notifications (and to resume the notifications eventually sent during the disconnection period).

However right now the server still errors out if there's more that one SSE stream. Should this be fixed? Is this even the right interpretation of the spec?

paoloricciuti · 2025-11-18T11:51:10Z

src/server/streamableHttp.test.ts

+        const primingEventId = primingIdMatch![1];
+
+        // Server closes the stream to trigger polling
+        transport.closeSSEStream(100);


To me it would feel very weird to have a closeSSEStream on the server that should have no knowledge of sessions let alone streams.

A bunch of frameworks dont give the user easy access to the transport but they do the server. Proxy by reference is good

This is a good point but maybe the right API is to expose the transport from the server?

src/server/streamableHttp.test.ts

jonathanhefner

would love feedback on whether this accurately captures the intent of your original SEP

Yes, looks great! Thank you! 😃

jonathanhefner · 2025-11-18T21:10:18Z

src/server/streamableHttp.test.ts

+        toolResolve!();
+
+        // Give the tool time to complete and store the result
+        await new Promise(resolve => setTimeout(resolve, 50));


Not sure if this is a concern, but this could lead to flaky tests. I'm not sure what we could await as an alternative though.

Addresses PR feedback from paoloricciuti requesting test coverage for the scenario where multiple messages are sent while the SSE client is disconnected. Uses a batch of tool calls to generate multiple responses that get stored and replayed on reconnection.

felixweinberger · 2025-11-19T00:21:57Z

So we actually had a brief discussion about this on discord and I think the spec should be clearer here: from the discussion we had the reconnection should be different from the standalone stream. So if the client was doing two POST requests each POST would have it's own lastEventId.

On reconnect this should basically result in 3 new GET SSE streams, two to get the remaining notificiations/responses from the POST requests and one as a standalone stream for the new notifications (and to resume the notifications eventually sent during the disconnection period).

However right now the server still errors out if there's more that one SSE stream. Should this be fixed? Is this even the right interpretation of the spec?

Ack, after the discusson on Discord seems clear we need to not error out on multiple streams. Still figuring out the right way to do that on this PR, will come back with an update soon, moving to draft for now.

- Fix replayEvents to use streamId from last-event-id header - Add conflict check per streamId (not global) - Add missing close handler to clean up stream mapping - Add test demonstrating concurrent GET streams resuming different POST streams This aligns with the spec: "The client MAY remain connected to multiple SSE streams simultaneously."

felixweinberger · 2025-11-19T00:56:17Z

Horrible timeout based tests - but looking for feedback on the implementation before figuring out prettier tests.

- Add closeStandaloneSSEStream() method to allow server to close the standalone GET notification stream, triggering client reconnection - Send priming event with retry field on GET streams (when eventStore configured) for resumability - Add tests for GET stream priming events and closeStandaloneSSEStream - Fix flaky test timeout for POST SSE polling test

felixweinberger · 2025-11-21T19:53:39Z

@felixweinberger will this require any changes to the Inspector or will it just be contained within SDK operations?

I think there should not be any changes required - this is primarily about server behavior, the SDK should handle resumption automatically.

If we wanted to have some debugging insight into resumption / reconnection though that seems like it might be valuable? E.g. surfacing reconnection events, showing the polling, showing retry intervals`, showing when a server actually did choose to disconnect.

cliffhall · 2025-11-21T20:00:04Z

@felixweinberger will this require any changes to the Inspector or will it just be contained within SDK operations?

I think there should not be any changes required - this is primarily about server behavior, the SDK should handle resumption automatically.

If we wanted to have some debugging insight into resumption / reconnection though that seems like it might be valuable? E.g. surfacing reconnection events, showing the polling, showing retry intervals`, showing when a server actually did choose to disconnect.

Would we need a demo server to generate some of this behavior, or is there one in the SDK examples we could use to test with?

felixweinberger · 2025-11-21T20:00:45Z

@felixweinberger will this require any changes to the Inspector or will it just be contained within SDK operations?

I think there should not be any changes required - this is primarily about server behavior, the SDK should handle resumption automatically.
If we wanted to have some debugging insight into resumption / reconnection though that seems like it might be valuable? E.g. surfacing reconnection events, showing the polling, showing retry intervals`, showing when a server actually did choose to disconnect.

Would we need a demo server to generate some of this behavior, or is there one in the SDK examples we could use to test with?

Good point, let me see if I can make an exampleServer...

Per SEP-1699, clients should auto-reconnect via GET when server closes POST SSE streams mid-operation. This enables polling for long-running tool calls. Changes: - Enable isReconnectable=true for POST SSE streams in client - Add example client demonstrating SSE polling with server - Update test to expect GET reconnection after POST stream fails

The isReconnectable=true change was too aggressive - per SEP-1699, reconnection should only happen after server sends a priming event with an event ID, not on all POST stream failures. Keep the example client for now; proper reconnection logic TBD.

felixweinberger · 2025-11-23T21:00:28Z

@cliffhall added src/examples/client/ssePollingClient.ts and src/examples/server/ssePollingExample.ts which demonstrate the feature together.

Per SEP-1699, servers may close SSE streams after sending a priming event with an event ID. This change enables automatic reconnection for POST-initiated streams once they've received at least one event with an ID. The change introduces `hasPrimingEvent` tracking in `_handleSseStream`: - GET streams remain always reconnectable (isReconnectable=true) - POST streams become reconnectable after receiving an event with ID - Reconnection uses `canResume = isReconnectable || hasPrimingEvent` This enables the SSE polling example client to work correctly with server-initiated disconnection and automatic client reconnection.

felixweinberger · 2025-11-23T21:12:31Z

src/integration-tests/taskResumability.test.ts


-            // Resume the notification stream using lastEventId
-            // This is the key part - we're resuming the same long-running tool using lastEventId
-            await client2.request(


This test was actually not spec compliant - we were doing a second post request to continue.

The spec actually requires all resumption requests to be GET requests.

paoloricciuti · 2025-11-23T21:28:09Z

Sorry I was at my company off-site and couldn't review it properly, will take a look tomorrow

mattzcarey · 2025-11-24T16:59:33Z

src/client/streamableHttp.ts

     * @param lastEventId The ID of the last received event for resumability
     * @param attemptCount Current reconnection attempt count for this specific stream
     */
    private _scheduleReconnection(options: StartSSEOptions, attemptCount = 0): void {


not for this PR but it would be good to be able to overwrite this method. For clients which aren't running all the time this will need some input externally from the client itself to wake it up.

Good idea, made an issue for now #1162

src/client/streamableHttp.ts

src/server/streamableHttp.ts

mattzcarey · 2025-11-24T17:13:11Z

src/server/streamableHttp.ts

-            this._streamMapping.set(streamId, res);
+
+            // Use streamId from getStreamIdForEventId if available, otherwise from replay
+            const finalStreamId = streamId ?? replayedStreamId;


could you explain this logic for me? I'm not sure I understand why the choice in ids. Wouldnt we only do this is the replayed one is now closed.

If getStreamIdForEventId is implemented: We use streamId from that lookup. This is the "proper" way - the event store explicitly tells us which stream the event belongs to, and we've already done conflict checking with this ID at line 403. We need this to be able to identify the correct stream encoded in the ID.

If getStreamIdForEventId isn't implemented (for backwards compat): streamId will be undefined, so we fall back to replayedStreamId returned from replayEventsAfter. This allows older event store implementations that don't implement the optional method to still work.

Actually, thinking through this again - I think I see what you're saying, we don't actually need streamId ?? replayedStreamId because there isn't really a case where streamId != replayedStreamId if getStreamIdForEventId is implemented correctly.

So we could probably simplify the below to just directly reference replayedStreamId.

Pushed a commit to update this, lmk what you think.

mattzcarey

Tentative approval

- Fix _scheduleReconnection comment: delay can now come from server retry field, not just exponential backoff - Fix getStreamIdForEventId comment: SDK doesn't parse streamId::... format, it uses replayEventsAfter return value as fallback

Always use replayedStreamId from replayEventsAfter instead of preferring streamId from getStreamIdForEventId. Both should return the same value for a correctly implemented event store, and replayEventsAfter is the authoritative source since it's the required method.

findleyr

Hi! Just a few comments as I compared this to what I was planning for the Go SDK. Feel free to disregard, though I'm curious of your thoughts in any case.

findleyr · 2025-11-24T21:39:46Z

src/examples/server/ssePollingExample.ts

+
+        // Server decides to disconnect the client to free resources
+        // Client will reconnect via GET with Last-Event-ID after retryInterval
+        const transport = transports.get(extra.sessionId!);


For the Go SDK, I was considering adding a (possibly nil) callback on extra, to avoid this type of coupling between tool and transport. Would that be valuable here?

findleyr · 2025-11-24T21:40:05Z

src/server/streamableHttp.ts

+     * Close an SSE stream for a specific request, triggering client reconnection.
+     * Use this to implement polling behavior during long-running operations -
+     * client will reconnect after the retry interval specified in the priming event.
+     */


Nit: should this operation only be valid if there's an event store?
I don't actually know, but it seems a bit problematic that the tool has to be aware both that it's being served on a streamable transport, and that this transport has an event store.

If the intent is to implement this in the actual tool, then it might be better to pass a callback in the request extra.

Should closeSSEStream take a retry duration? Again, if we're delegating control over this to the tool, one can imagine that the tool would want to be able to control its own replay pacing, and that the retry timeout for one tool might not be appropriate for another.

felixweinberger mentioned this pull request Nov 17, 2025

feat: add conformance tests for SEP-1699 SSE polling modelcontextprotocol/conformance#35

Closed

9 tasks

felixweinberger closed this Nov 17, 2025

felixweinberger reopened this Nov 17, 2025

felixweinberger force-pushed the fweinberger/sep-1699 branch 4 times, most recently from ebd4179 to 0b61e98 Compare November 17, 2025 21:02

felixweinberger commented Nov 17, 2025

View reviewed changes

felixweinberger linked an issue Nov 18, 2025 that may be closed by this pull request

Implement SEP-1699: Support SSE Polling via Server-Side Disconnect #1061

Open

felixweinberger force-pushed the fweinberger/sep-1699 branch from a556d78 to 6368bfa Compare November 18, 2025 11:07

felixweinberger force-pushed the fweinberger/sep-1699 branch from 6368bfa to 464b1f8 Compare November 18, 2025 11:16

felixweinberger marked this pull request as ready for review November 18, 2025 11:29

felixweinberger requested a review from a team as a code owner November 18, 2025 11:29

felixweinberger requested a review from jonathanhefner November 18, 2025 11:29

paoloricciuti reviewed Nov 18, 2025

View reviewed changes

jonathanhefner reviewed Nov 18, 2025

View reviewed changes

felixweinberger marked this pull request as draft November 19, 2025 00:22

felixweinberger force-pushed the fweinberger/sep-1699 branch from 151614e to 6d32c15 Compare November 19, 2025 00:53

felixweinberger marked this pull request as ready for review November 19, 2025 00:56

felixweinberger mentioned this pull request Nov 19, 2025

Clarify scope of SEP-1699: SSE Polling modelcontextprotocol/modelcontextprotocol#1847

Closed

felixweinberger added 2 commits November 20, 2025 14:51

chore: remove SEP-1699 references from test comments

78d116f

felixweinberger force-pushed the fweinberger/sep-1699 branch from d9761b6 to 8cbb07e Compare November 21, 2025 17:52

Merge branch 'main' into fweinberger/sep-1699

7ad9c84

felixweinberger mentioned this pull request Nov 21, 2025

feat: add conformance tests for SEP-1699 SSE polling modelcontextprotocol/conformance#47

Merged

4 tasks

felixweinberger requested review from bhosmer-ant and pcarleton and removed request for paoloricciuti November 21, 2025 18:09

felixweinberger and others added 6 commits November 23, 2025 20:30

Add SSE polling example server demonstrating SEP-1699

b3660c3

Add test for multiple notifications sent while client is disconnected

0ee7e2e

Fix: pass pre-parsed body to handleRequest

f4e736e

Merge branch 'main' into fweinberger/sep-1699

220a854

felixweinberger commented Nov 23, 2025

View reviewed changes

chore: restore original getReader() line placement in tests

6335cf4

mattzcarey reviewed Nov 24, 2025

View reviewed changes

src/client/streamableHttp.ts Outdated Show resolved Hide resolved

mattzcarey reviewed Nov 24, 2025

View reviewed changes

src/server/streamableHttp.ts Show resolved Hide resolved

mattzcarey reviewed Nov 24, 2025

View reviewed changes

src/server/streamableHttp.ts Outdated Show resolved Hide resolved

mattzcarey reviewed Nov 24, 2025

View reviewed changes

mattzcarey approved these changes Nov 24, 2025

View reviewed changes

felixweinberger mentioned this pull request Nov 24, 2025

Allow customizable reconnection behavior for non-persistent clients #1162

Open

findleyr reviewed Nov 24, 2025

View reviewed changes

feat: implement SEP-1699 SSE polling via server-side disconnect #1129

Are you sure you want to change the base?

feat: implement SEP-1699 SSE polling via server-side disconnect #1129

Conversation

felixweinberger commented Nov 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Uh oh!

pkg-pr-new bot commented Nov 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mattzcarey Nov 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

felixweinberger commented Nov 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

paoloricciuti left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jonathanhefner left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

felixweinberger commented Nov 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

felixweinberger commented Nov 19, 2025

Uh oh!

felixweinberger commented Nov 21, 2025

Uh oh!

cliffhall commented Nov 21, 2025

Uh oh!

felixweinberger commented Nov 21, 2025

Uh oh!

felixweinberger commented Nov 23, 2025

Uh oh!

felixweinberger Nov 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

paoloricciuti commented Nov 23, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

felixweinberger Nov 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

felixweinberger Nov 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mattzcarey left a comment

Choose a reason for hiding this comment

felixweinberger commented Nov 17, 2025 •

edited

Loading

pkg-pr-new bot commented Nov 17, 2025 •

edited

Loading

mattzcarey Nov 18, 2025 •

edited

Loading

felixweinberger commented Nov 18, 2025 •

edited

Loading

felixweinberger commented Nov 19, 2025 •

edited

Loading

felixweinberger Nov 23, 2025 •

edited

Loading

felixweinberger Nov 24, 2025 •

edited

Loading

felixweinberger Nov 24, 2025 •

edited

Loading